# 板载功能库（mpython） ```{admonition} 本文引用的文件 :class: note - [docs/docs/zh_CN/library/mPython/mpython.rst](../../../../products/mpython/library/mPython/mpython.rst) - `firmware/port/boards/mpython/modules/mpython.py` - `docs/examples/display/helloworld.py` - `docs/examples/button/button_event.py` - `docs/examples/button/touchPad_notes.py` - [esp32s3/docs/5_api/library/mPython/mpython.rst](../../../../products/mpython-s3/5_api/library/mPython/mpython.rst) ``` ## 产品概述 本模块为 mPython 掌控板的板载功能封装，面向 K12 创客教育场景，提供开箱即用的显示、输入、传感器与网络能力。通过统一的 Python API，开发者可快速实现： - OLED/TFT 显示与绘图 - 按键与触摸事件处理 - 加速度计、陀螺仪、磁力计等运动感知 - 光线与声音采集 - WiFi 连接与热点模式 - RGB 灯控制与工具函数 该模块屏蔽了底层 I2C/ADC/PWM/TouchPad 等硬件细节，使初学者也能以直观方式完成交互项目。 **Section sources** - [docs/docs/zh_CN/library/mPython/mpython.rst:1-10](../../../../products/mpython/library/mPython/mpython.rst) ## 核心业务流程 - 初始化流程：模块加载时自动创建全局对象（如 oled、light、sound、button_a/b、touchPad_*、rgb），并检测可用设备（OLED、MOTION、Magnetic）。 - 显示流程：调用 DispChar/DispChar_font 写入帧缓冲，show() 刷新到屏幕；支持自动换行与多种文本模式。 - 输入流程：Button/Touch 通过中断回调或轮询读取状态，支持按下/释放事件与计数。 - 传感器流程：Accelerometer/Gyroscope/Magnetic 通过 I2C 读取原始数据并进行单位换算、偏移校准与角度计算。 - 网络流程：wifi.connectWiFi 扫描并连接 AP；enable_APWiFi 开启热点；disconnectWiFi/disable_APWiFi 关闭连接/AP。 ```text sequenceDiagram participant App as "用户程序" participant MP as "mpython 模块" participant HW as "I2C/ADC/PWM/TouchPad" participant OLED as "SSD1106/OLED" participant NET as "network.WLAN" App->>MP : 导入 mpython MP->>HW : 初始化 I2C/ADC/PWM/TouchPad MP->>OLED : 检测并实例化 OLED(128x64) MP->>MP : 创建 light/sound/button/touchpad/rgb App->>MP : oled.DispChar("你好", x, y) MP->>OLED : 写入字符位图到帧缓冲 App->>MP : oled.show() MP->>OLED : 刷新显示 App->>MP : wifi.connectWiFi(ssid, pwd) MP->>NET : 扫描并连接 STA Note over MP,NET : 超时则抛出异常 ``` **Diagram sources** - `firmware/port/boards/mpython/modules/mpython.py:91-204` - `firmware/port/boards/mpython/modules/mpython.py:1205-1254` **Section sources** - `firmware/port/boards/mpython/modules/mpython.py:91-204` - `firmware/port/boards/mpython/modules/mpython.py:1205-1254` ## 功能模块清单 - 显示 - OLED 类：DispChar/DispChar_font/fill/pixel/scroll/blit/text/rect/hline/vline/line/show/poweron/poweroff/contrast/invert - ESP32-S3 TFT_displayer：DispChar/DispChar_font/clear/show（ST7789 LCD，320x172） - 输入 - Button：is_pressed/was_pressed/get_presses/value/status/event_pressed/event_released/irq - Touch：config/is_pressed/was_pressed/get_presses/read/event_pressed/event_released - 传感器 - Accelerometer：get_x/y/z/set_range/set_resolution/set_offset/roll_pitch_angle/事件常量 - Gyroscope：get_x/y/z/set_range/set_ODR/set_offset - Magnetic：get_x/y/z/get_field_strength/get_heading/calibrate/peeling/clear_peeling - 环境传感 - LightSensor（可选）：value（lux 换算） - BME280（可选）：temperature/pressure/humidity - 音频 - music：play/pitch/stop/set_tempo/get_tempo/reset（内置曲目） - audio（ESP32）：player_init/play/pause/resume/stop/set_volume/player_status/player_deinit；录音与TTS - 网络 - wifi：connectWiFi/disconnectWiFi/enable_APWiFi/disable_APWiFi - 其他 - rgb：NeoPixel 派生，write/fill/brightness - MPythonPin：read_digital/write_digital/read_analog/write_analog/irq - 工具：sleep/sleep_ms/sleep_us/numberMap/uuid **Section sources** - [docs/docs/zh_CN/library/mPython/mpython.rst:52-757](../../../../products/mpython/library/mPython/mpython.rst) - [esp32s3/docs/5_api/library/mPython/mpython.rst:182-221](../../../../products/mpython-s3/5_api/library/mPython/mpython.rst) - `firmware/port/boards/mpython/modules/mpython.py:91-204` - `firmware/port/boards/mpython/modules/mpython.py:206-641` - `firmware/port/boards/mpython/modules/mpython.py:643-1007` - `firmware/port/boards/mpython/modules/mpython.py:1113-1420` ## 数据与状态 - 显示缓冲区 - OLED：128x64 单色帧缓冲，字符位图来自内嵌字体；DispChar 返回 (宽度, 下一坐标) 便于连续排版。 - TFT_displayer：RGB565 帧缓冲，支持颜色绘制与自定义字体。 - 传感器数据 - 加速度：mg 单位，范围±2/4/8/16g，分辨率10/12/14bit；roll/pitch 由三轴向量归一化计算。 - 角速度：°/s，量程±16~2048dps；支持 ODR 设置与偏移持久化。 - 磁场：mG 单位，强度为三轴矢量和；heading 基于 atan2 计算，需水平放置与校准。 - 输入状态 - Button/Touch：维护“是否按下”“上次按下”“计数”状态；中断触发后通过 schedule 调度回调。 - 网络状态 - STA/AP 双接口；连接过程包含扫描、认证、DHCP 等待与超时处理。 ```text classDiagram class MOTION { +Accelerometer +Gyroscope } class Accelerometer { +get_x() +get_y() +get_z() +set_range() +set_resolution() +set_offset() +roll_pitch_angle() } class Gyroscope { +get_x() +get_y() +get_z() +set_range() +set_ODR() +set_offset() } class Magnetic { +get_x() +get_y() +get_z() +get_field_strength() +get_heading() +calibrate() +peeling() +clear_peeling() } MOTION --> Accelerometer : "组合" MOTION --> Gyroscope : "组合" ``` **Diagram sources** - `firmware/port/boards/mpython/modules/mpython.py:206-641` - `firmware/port/boards/mpython/modules/mpython.py:643-1007` **Section sources** - `firmware/port/boards/mpython/modules/mpython.py:206-641` - `firmware/port/boards/mpython/modules/mpython.py:643-1007` ## 关键约束与边界 - 引脚限制 - P4 用于光线传感器，P10 用于声音传感器，不可用作通用 IO。 - PWM/ANALOG/OUT_DRAIN 对引脚有明确支持列表，非法模式将抛 TypeError。 - 传感器可用性 - OLED 仅在 I2C 地址 0x60 存在时初始化；MOTION 需检测到 MSA300/QMI8658C；Magnetic 需检测到 MMC5983MA/MMC5603NJ。 - 精度与环境 - 仅用加速度计算的 roll/pitch 适用于静态重力场景；强振动会引入误差。 - 磁力计 heading 需保持水平并校准，避免强磁干扰。 - 网络行为 - connectWiFi 默认超时 10 秒，失败抛 OSError；AP 模式可配置信道与密码。 - 版本差异 - v2.3+ 移除加速度计运动侦测事件；ESP32-S3 使用 TFT_displayer 替代 OLED。 **Section sources** - `firmware/port/boards/mpython/modules/mpython.py:1125-1186` - `firmware/port/boards/mpython/modules/mpython.py:200-204` - `firmware/port/boards/mpython/modules/mpython.py:1205-1254` - [docs/docs/zh_CN/library/mPython/mpython.rst:129-191](../../../../products/mpython/library/mPython/mpython.rst) ## 详细API说明 ### OLED 显示（ESP32） - 类与方法 - DispChar(s, x, y, mode=TextMode.normal, auto_return=False)：显示多语言字符，mode 支持 normal/rev/trans/xor；auto_return 启用自动换行。 - DispChar_font(font, s, x, y, invert=False)：使用 font_to_py 转换的自定义字体显示。 - fill/pixel/scroll/blit/text/rect/hline/vline/line：继承 framebuf 绘图能力。 - poweron/poweroff/contrast/invert：电源与对比度控制。 - 示例 - 多语言 hello world 显示见示例文件。 ```text flowchart TD Start(["调用 DispChar"]) --> LoadFont["读取字符位图"] LoadFont --> Mode{"文本模式"} Mode --> |normal| DrawWhite["写白色像素"] Mode --> |rev| DrawBlack["写黑色像素"] Mode --> |trans| Overlay["叠加到已有内容"] Mode --> |xor| Xor["翻转背景像素"] DrawWhite --> NextChar["下一个字符"] DrawBlack --> NextChar Overlay --> NextChar Xor --> NextChar NextChar --> End(["返回(宽度, 下一坐标)"]) ``` **Diagram sources** - `firmware/port/boards/mpython/modules/mpython.py:100-164` **Section sources** - [docs/docs/zh_CN/library/mPython/mpython.rst:485-579](../../../../products/mpython/library/mPython/mpython.rst) - `docs/examples/display/helloworld.py:1-7` - `firmware/port/boards/mpython/modules/mpython.py:91-198` ### 按键与触摸 - Button - is_pressed/was_pressed/get_presses/value/status：查询当前/历史状态与计数。 - event_pressed/event_released：注册回调，内部通过 Pin.irq 触发。 - irq：支持下降沿/上升沿/电平触发。 - Touch - config(threshold)：设置触摸阈值。 - read/is_pressed/was_pressed/get_presses：读取原始值与状态。 - event_pressed/event_released：触摸事件回调。 - 示例 - 按键事件回调与触摸按键播放音阶示例。 ```text sequenceDiagram participant User as "用户" participant Btn as "Button/Touch" participant IRQ as "Pin.irq" participant App as "应用回调" User->>Btn : 按下/释放 Btn->>IRQ : 触发中断 IRQ-->>Btn : 回调 handler Btn->>App : 调用 event_pressed/event_released App-->>User : 执行业务逻辑 ``` **Diagram sources** - `firmware/port/boards/mpython/modules/mpython.py:1270-1382` **Section sources** - [docs/docs/zh_CN/library/mPython/mpython.rst:325-453](../../../../products/mpython/library/mPython/mpython.rst) - `docs/examples/button/button_event.py:1-18` - `docs/examples/button/touchPad_notes.py:1-34` - `firmware/port/boards/mpython/modules/mpython.py:1270-1382` ### 加速度计、陀螺仪、磁力计 - Accelerometer - get_x/y/z：返回 mg 单位；set_range/set_resolution 配置量程与分辨率；set_offset 校准偏移；roll_pitch_angle 计算欧拉角。 - 事件常量：tilt_left/right/up/down、face_up/down、single/double click、freefall（v2.3+ 移除事件）。 - Gyroscope - get_x/y/z：°/s；set_range/set_ODR 配置量程与输出速率；set_offset 校准。 - Magnetic - get_x/y/z：mG；get_field_strength：矢量模；get_heading：航向角（需水平与校准）；calibrate：引导旋转校准；peeling/clear_peeling：去皮/恢复。 ```text flowchart TD A["读取三轴加速度"] --> N["归一化向量"] N --> R["roll = -asin(y)"] N --> P["pitch = atan2(x, z)"] R --> Out["返回 (roll, pitch)"] P --> Out ``` **Diagram sources** - `firmware/port/boards/mpython/modules/mpython.py:497-507` **Section sources** - [docs/docs/zh_CN/library/mPython/mpython.rst:69-237](../../../../products/mpython/library/mPython/mpython.rst) - [esp32s3/docs/5_api/library/mPython/mpython.rst:182-221](../../../../products/mpython-s3/5_api/library/mPython/mpython.rst) - `firmware/port/boards/mpython/modules/mpython.py:251-641` - `firmware/port/boards/mpython/modules/mpython.py:643-1007` ### 光线与声音 - 光线 - light.read()：ADC 原始值 0~4095；LightSensor.value()（可选）：转换为 lux。 - 声音 - sound.read()：ADC 原始值 0~4095；audio.loudness()（ESP32）：录音响度。 **Section sources** - [docs/docs/zh_CN/library/mPython/mpython.rst:56-67](../../../../products/mpython/library/mPython/mpython.rst) - `firmware/port/boards/mpython/modules/mpython.py:1261-1267` ### 网络（WiFi） - wifi.connectWiFi(ssid, passwd, timeout=10)：扫描并连接，超时抛异常。 - wifi.disconnectWiFi()：断开并关闭 STA。 - wifi.enable_APWiFi(essid, password=b'', channel=10)：开启热点。 - wifi.disable_APWiFi()：关闭热点。 ```text sequenceDiagram participant App as "应用" participant W as "wifi" participant N as "network.WLAN" App->>W : connectWiFi(ssid, pwd) W->>N : sta.scan() W->>N : sta.connect(ssid, pwd) loop 等待IP W->>N : ifconfig() end alt 成功 W-->>App : 打印连接信息 else 超时 W-->>App : 抛出OSError end ``` **Diagram sources** - `firmware/port/boards/mpython/modules/mpython.py:1205-1254` **Section sources** - [docs/docs/zh_CN/library/mPython/mpython.rst:720-757](../../../../products/mpython/library/mPython/mpython.rst) - `firmware/port/boards/mpython/modules/mpython.py:1205-1254` ### RGB 灯与引脚 - rgb：NeoPixel 派生，write/fill/brightness 控制 3 颗 WS2812。 - MPythonPin：支持 IN/OUT/PWM/ANALOG/OUT_DRAIN；read_digital/write_digital/read_analog/write_analog/irq；注意 P4/P10 保留给传感器。 **Section sources** - [docs/docs/zh_CN/library/mPython/mpython.rst:454-484](../../../../products/mpython/library/mPython/mpython.rst) - [docs/docs/zh_CN/library/mPython/mpython.rst:649-718](../../../../products/mpython/library/mPython/mpython.rst) - `firmware/port/boards/mpython/modules/mpython.py:1257-1267` - `firmware/port/boards/mpython/modules/mpython.py:1113-1186` ## 依赖分析 - 底层依赖 - machine.I2C/ADC/PWM/TouchPad/Pin：硬件抽象层。 - ssd1106.SSD1106_I2C：OLED 驱动。 - neopixel.NeoPixel：RGB 灯控制。 - framebuf：帧缓冲绘图基础。 - network.WLAN：WiFi 网络栈。 - NVS：存储加速度/陀螺仪偏移。 - 模块耦合 - mpython.py 集中管理全局对象与传感器初始化，各子模块（OLED/MOTION/Magnetic/Button/Touch）通过 i2c/adc/pwm 访问硬件。 - 事件系统通过 micropython.schedule 在安全上下文中调用用户回调。 ```text graph TB MP["mpython.py"] --> SSD["ssd1106"] MP --> FB["framebuf"] MP --> NP["neopixel"] MP --> NET["network.WLAN"] MP --> NVS["NVS"] MP --> I2C["machine.I2C"] MP --> ADC["machine.ADC"] MP --> PWM["machine.PWM"] MP --> TP["machine.TouchPad"] ``` **Diagram sources** - `firmware/port/boards/mpython/modules/mpython.py:11-24` **Section sources** - `firmware/port/boards/mpython/modules/mpython.py:11-24` ## 性能与最佳实践 - 显示优化 - 批量绘制后统一 show()，减少频繁刷新。 - 使用 auto_return 自动换行简化排版。 - 传感器采样 - 合理设置量程与分辨率，平衡精度与功耗。 - 使用 set_offset 与 calibrate 提升测量准确性。 - 输入响应 - 优先使用事件回调降低轮询开销。 - 触摸阈值根据环境调整，避免误触。 - 网络 - 连接前确认 SSID 与密码正确，必要时增加重试与超时策略。 - 不使用 WiFi 时及时 disconnect/disable AP 以降低功耗。 [本节为通用指导，不直接分析具体文件] ## 故障排查 - OLED 未显示 - 检查 I2C 地址 0x60 是否存在；确认 oled.init 与 show() 调用。 - 传感器无数据 - 检查 MOTION/Magnetic 初始化是否成功；确认 I2C 总线正常。 - 按键/触摸无响应 - 检查引脚映射与上拉配置；确认事件回调已注册。 - WiFi 连接失败 - 检查 SSID/密码与时区；查看超时日志；尝试 disable AP 后再连接。 **Section sources** - `firmware/port/boards/mpython/modules/mpython.py:200-204` - `firmware/port/boards/mpython/modules/mpython.py:1205-1254` ## 结论 mpython 模块为掌控板提供了完整且易用的板载功能封装，覆盖显示、输入、传感器与网络等核心能力。通过清晰的 API 与丰富的示例，开发者可以快速构建交互项目。建议在实际项目中结合传感器校准、事件驱动与资源管理，以获得稳定高效的体验。 [本节为总结性内容，不直接分析具体文件]